TrackWindowProxyFromExistingDrag

Allows custom handling of the drag process when the user drags a proxy icon.

pascal OSStatus TrackWindowProxyFromExistingDrag (
                     WindowPtr window,
                     Point startPt,
                     DragReference drag,
                     RgnHandle inDragOutlineRgn);

window

A value of type WindowPtr . Pass a pointer to the window whose proxy icon is being dragged.

startPt

A structure of type Point . Before calling TrackWindowProxyFromExistingDrag , your application should set the Point structure to contain the point, specified in global coordinates, where the mouse-down event that began the drag occurred. Your application may retrieve this value from the where field of the event structure.

drag

A value of type DragReference that refers to the current drag process. Pass in the value produced in the outNewDrag parameter of the function BeginWindowProxyDrag . If you are not using BeginWindowProxyDrag in conjunction with TrackWindowProxyFromExistingDrag , you must create the drag reference yourself with the Drag Manager function NewDrag .

inDragOutlineRgn

A value of type RgnHandle . Pass in a region handle representing an outline of the icon being dragged. You may obtain a handle to this region from the outDragOutlineRgn parameter of BeginWindowProxyDrag . If you are not using BeginWindowProxyDrag in conjunction with TrackWindowProxyFromExistingDrag , you must create the region yourself.

function result

A result code. See Result Codes. Errors are also returned from the Drag Manager, including userCanceledErr (-128).

DISCUSSION

Typically, if the proxy icon represents a type of object (currently, file system entities such as files, folders, and volumes) supported by the Window Manager, the Window Manager can handle all aspects of the drag process itself, and your application should call the function TrackWindowProxyDrag . However, if the proxy icon represents a type of data that the Window Manager does not support, or if you wish to implement custom dragging behavior, your application should call the TrackWindowProxyFromExistingDrag function.

The TrackWindowProxyFromExistingDrag function accepts an existing drag reference and adds file data if the window contains a file proxy. If your application uses TrackWindowProxyFromExistingDrag , you then have the choice of using this function in conjunction with the functions BeginWindowProxyDrag and EndWindowProxyDrag or simply calling TrackWindowProxyFromExistingDrag and handling all aspects of creating and disposing of the drag yourself.

Your application detects a drag when the function FindWindow returns the inProxyIcon result code; see FindWindow Result Code Constant for the Proxy Icon for more details.

See Supporting Window Proxy Icons for examples of how your application can provide proxy icon support in its document windows.

VERSION NOTES

Available with Mac OS 8.5 and later.